RWTS CALLER ...................................by Bill Morgan

Here is a routine to directly call RWTS (Read/Write Track/Sector), the subroutine in DOS that actually reads fro or writes to the disk.  Many programs use a routine like this to handle disk I/O, without all the time-consuming overhead of the DOS file manager.

All you need to do to use RWTS directly is to place certain information into an Input/Output control Block (IOB), and tell RWTS where the IOB is.  Following is an explanation of the IOB (the addresses are those of DOS's own IOB; you can use it yourself, or build your own wherever is convenient):

!lm+5
Address        Description

$B7E8      Table type, always $01
$B7E9      Slot number times 16, usually $60
$B7EA      Drive number, $01 or $02
$B7EB      Volume number expected, $00 matches anything
$B7EC      Track number, $00 through $22
$B7ED      Sector number, $00 through $0F
$B7EE-F    Address of Device Characteristics Table,
           $B7FB for DOS's own DCT
$B7F0-1    Address of buffer, wherever you want
$B7F2      Not used
$B7F3      Byte count if partial sector, $00 normally
$B7F4      Command     $00 = SEEK
                       $01 = READ
                       $02 = WRITE
                       $04 = FORMAT
$B7F5      Error Code  $00 = No errors
                       $08 = Error in initialization
                       $10 = Write protect error
                       $20 = Volume mismatch
                       $40 = Drive error
$B7F6      Last volume number
$B7F7      Last slot number
$B7F8      Last drive number

!lm-5
The Device Characteristics Table (whose address is at $B7EE,EF) is a four-byte block containing information about the disk drive.  For a standard Apple Disk II this block always contains $00 01 EF D8.

For our purposes, the most important items in the IOB are track, sector, buffer address, and command.  By manipulating these, you can read any sector of the disk into any area of memory.  All you need to do is set up the IOB, load the A- and Y-registers with the address of the IOB, and JSR $3D9.  And if you decide to use the file manager's IOB, you can even set up the A- and Y-registers by a simple JSR $3E3.

RWTS will read the track and sector you choose into your 256-byte buffer.  If there was a disk error, RWTS will return with the carry bit set and an error code stored in the IOB.  It is then up to the user's program to decide what to do about the error.  If there was no error, carry will be clear.

This month we'll set up a short program using the RWTS Caller to read an entire track of the disk into 16 consecutive pages of memory.  DOS stores information on a track starting at sector $0F and working back to sector $00, so we must read a sector into the buffer, decrement the sector in the IOB, and increment the buffer pointer.

RWTS.CALLER:
!lm+5

Lines 1680-1850 set up the IOB, transferring values from the program variables.

Lines 1870-1890 load the address of the IOB and call RWTS.

Lines 1900-1910 are necessary to avoid confusing the system monitor.  (RWTS and the monitor both use location $48.)

Lines 1960-2030 ring a warning if a disk error occurred, and display the error code.
!lm-5

TRACK READ:
!lm+5

Lines 1260-1350 initialize the variables and call input routines.

Lines 1370-1440 read the sectors from $0f through $00 into the buffer.  Line 1410 will end the program if an error occurred.

Line 1460 will become a display routine.  (Or, whatever processing you want to do on the buffer.)

Lines 1500-1650 will become input routines; right now they just set the track, buffer and command variables.

!lm-5
CAUTIONS:
!lm+5

1) These routines have very little error-checking.  It is very easy to make a trivial error and lose information from a diskette.  Always test an RWTS-calling program on a diskette yhou don't care about.

2) If you store information on a blank area of a diskette using these techniques, DOS doesn't know you have taken some space.  Unless you modify the VTOC to show that sectors are used, DOS can overwrite your data.  (What's a VTOC?, you say.  Volume Table of Contents.  We'll go into that another time.)

!lm-5
There is more about RWTS on pages 94-98 of Apple DOS Manual, and a goldmine of information in Beneath Apple DOS, by Don Worth and Pieter Lechner. (Quality Software, 1981.)
